<html>
  
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="../../style.css">
    <base target="_parent">
    <title data-trilium-title>Using promoted attributes to configure scripts</title>
  </head>
  
  <body>
    <div class="content">
       <h1 data-trilium-h1>Using promoted attributes to configure scripts</h1>

      <div class="ck-content">
        <p>A good use case of promoted attributes is to easily define the various
          parameters a script might need, for example an input and output note if
          it's processing data, or a checkbox to define a particular change in behavior
          for the script.</p>
        <p>
          <img src="Using promoted attributes .png" width="425" height="179">
        </p>
        <h2>Using check boxes to toggle flags</h2>
        <p>Instead of asking the user to modify a boolean value in the script, it's
          much more intuitive to use a checkbox for it as a promoted attribute.</p>
        <p>To do so, first define the promoted attribute:</p><pre><code class="language-text-x-trilium-auto">#label:groupByExtension="promoted,alias=Group by extension,single,boolean"</code></pre>
        <p>Then use it:</p><pre><code class="language-application-javascript-env-frontend">const byExtension = api.currentNote.getLabelValue("groupByExtension") === "true";
if (byExtension) {
	// Do something.
}</code></pre>
        <p>This will work equally well in both front-end and back-end scripts.</p>
        <h2>Using relations to select notes</h2>
        <p>One common use case for a script is to read data from another note and
          perhaps output its result in another note. To do so we need to define the
          following promoted attributes:</p><pre><code class="language-text-x-trilium-auto">#relation:input="promoted,alias=Input,single" #relation:output="promoted,alias=Output,single"</code></pre>
        <p>Once we have this, we can add some basic error handling to ensure that
          the fields are completed by the user:</p><pre><code class="language-text-x-trilium-auto">const inputNoteId = api.currentNote.getRelationValue("input");   
if (!inputNoteId) {
	api.showError("Missing input.");
    return;
}

const outputNoteId = api.currentNote.getRelationValue("output");
if (!outputNoteId) {
    api.showError("Missing output.");
    return;
}</code></pre>
        <p>Note that here we are using <code>api.showError</code> which is only available
          for frontend notes. If you are writing a backend note, simply remove <code>api.showError</code> but
          the user will no feedback on why the script did not execute properly.</p>
        <p>Afterwards we can simply read the note and do something with it:</p><pre><code class="language-text-x-trilium-auto">const note = api.getNote(inputNoteId);
if (!note) {
	return;
}
const content = note.getContent().toString("utf-8");</code></pre>
      </div>
    </div>
  </body>

</html>